From b83a4f2e1dc2507687840c2447ab54feba927a95 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Javier=20Jard=C3=B3n?= Date: Mon, 18 Apr 2011 00:24:56 +0100 Subject: [PATCH] Move documentation to inline comments: GtkToggleButton --- docs/reference/gtk/tmpl/.gitignore | 1 + docs/reference/gtk/tmpl/gtktogglebutton.sgml | 207 ------------------- gtk/gtktogglebutton.c | 102 ++++++++- 3 files changed, 101 insertions(+), 209 deletions(-) delete mode 100644 docs/reference/gtk/tmpl/gtktogglebutton.sgml diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index f1536e319b..de00d196f8 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -121,6 +121,7 @@ gtktexttag.sgml gtktexttagtable.sgml gtktextview.sgml gtktoggleaction.sgml +gtktogglebutton.sgml gtktoggletoolbutton.sgml gtktoolbar.sgml gtktoolbutton.sgml diff --git a/docs/reference/gtk/tmpl/gtktogglebutton.sgml b/docs/reference/gtk/tmpl/gtktogglebutton.sgml deleted file mode 100644 index 815d6a480b..0000000000 --- a/docs/reference/gtk/tmpl/gtktogglebutton.sgml +++ /dev/null @@ -1,207 +0,0 @@ - -GtkToggleButton - - -Create buttons which retain their state - - - -A #GtkToggleButton is a #GtkButton which will remain 'pressed-in' when -clicked. Clicking again will cause the toggle button to return to its -normal state. - - -A toggle button is created by calling either gtk_toggle_button_new() or -gtk_toggle_button_new_with_label(). If using the former, it is advisable to -pack a widget, (such as a #GtkLabel and/or a #GtkPixmap), into the toggle -button's container. (See #GtkButton for more information). - - -The state of a #GtkToggleButton can be set specifically using -gtk_toggle_button_set_active(), and retrieved using -gtk_toggle_button_get_active(). - - -To simply switch the state of a toggle button, use gtk_toggle_button_toggled. - - -Creating two <structname>GtkToggleButton</structname> widgets. - - -void make_toggles (void) { - GtkWidget *dialog, *toggle1, *toggle2; - - dialog = gtk_dialog_new (); - toggle1 = gtk_toggle_button_new_with_label ("Hi, i'm a toggle button."); - - /* Makes this toggle button invisible */ - gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle1), TRUE); - - g_signal_connect (toggle1, "toggled", - G_CALLBACK (output_state), NULL); - gtk_box_pack_start (GTK_BOX (GTK_DIALOG (dialog)->action_area), - toggle1, FALSE, FALSE, 2); - - toggle2 = gtk_toggle_button_new_with_label ("Hi, i'm another toggle button."); - gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle2), FALSE); - g_signal_connect (toggle2, "toggled", - G_CALLBACK (output_state), NULL); - gtk_box_pack_start (GTK_BOX (GTK_DIALOG (dialog)->action_area), - toggle2, FALSE, FALSE, 2); - - gtk_widget_show_all (dialog); -} - - - - - - - - - - #GtkButton - a more general button. - - - - #GtkCheckButton - another way of presenting a toggle option. - - - - #GtkCheckMenuItem - a #GtkToggleButton as a menu item. - - - - - - - - - - - - - -The #GtkToggleButton struct contains private data only, and should be manipulated using the functions below. - - - - - -Should be connected if you wish to perform an action whenever the -#GtkToggleButton's state is changed. - - -@togglebutton: the object which received the signal. - - - - - - - - - - - - - - - - - - -Creates a new toggle button. A widget should be packed into the button, as in gtk_button_new(). - - -@void: -@Returns: a new toggle button. - - - - -Creates a new toggle button with a text label. - - -@label: a string containing the message to be placed in the toggle button. -@Returns: a new toggle button. - - - - - - - -@label: -@Returns: - - - - - - -@toggle_button: -@draw_indicator: - - - - - - - -@toggle_button: -@Returns: - - - - -Emits the toggled -signal on the #GtkToggleButton. There is no good reason for an -application ever to call this function. - - -@toggle_button: a #GtkToggleButton. - - - - -Queries a #GtkToggleButton and returns its current state. Returns %TRUE if -the toggle button is pressed in and %FALSE if it is raised. - - -@toggle_button: a #GtkToggleButton. -@Returns: a #gboolean value. - - - - -Sets the status of the toggle button. Set to %TRUE if you want the -GtkToggleButton to be 'pressed in', and %FALSE to raise it. -This action causes the toggled signal to be emitted. - - -@toggle_button: a #GtkToggleButton. -@is_active: %TRUE or %FALSE. - - - - - - - -@toggle_button: -@Returns: - - - - - - - -@toggle_button: -@setting: - - diff --git a/gtk/gtktogglebutton.c b/gtk/gtktogglebutton.c index a05d98a9a8..586b7351ee 100644 --- a/gtk/gtktogglebutton.c +++ b/gtk/gtktogglebutton.c @@ -38,6 +38,58 @@ #include "gtkintl.h" +/** + * SECTION:gtktogglebutton + * @Short_description: Create buttons which retain their state + * @Title: GtkToggleButton + * @See_also: #GtkButton, #GtkCheckButton, #GtkCheckMenuItem + * + * A #GtkToggleButton is a #GtkButton which will remain 'pressed-in' when + * clicked. Clicking again will cause the toggle button to return to its + * normal state. + * + * A toggle button is created by calling either gtk_toggle_button_new() or + * gtk_toggle_button_new_with_label(). If using the former, it is advisable to + * pack a widget, (such as a #GtkLabel and/or a #GtkPixmap), into the toggle + * button's container. (See #GtkButton for more information). + * + * The state of a #GtkToggleButton can be set specifically using + * gtk_toggle_button_set_active(), and retrieved using + * gtk_toggle_button_get_active(). + * + * To simply switch the state of a toggle button, use gtk_toggle_button_toggled(). + * + * + * Creating two #GtkToggleButton widgets. + * + * void make_toggles (void) { + * GtkWidget *dialog, *toggle1, *toggle2; + * + * dialog = gtk_dialog_new (); + * toggle1 = gtk_toggle_button_new_with_label ("Hi, i'm a toggle button."); + * + * // Makes this toggle button invisible + * gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle1), TRUE); + * + * g_signal_connect (toggle1, "toggled", + * G_CALLBACK (output_state), NULL); + * gtk_box_pack_start (GTK_BOX (GTK_DIALOG (dialog)->action_area), + * toggle1, FALSE, FALSE, 2); + * + * toggle2 = gtk_toggle_button_new_with_label ("Hi, i'm another toggle button."); + * gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle2), FALSE); + * g_signal_connect (toggle2, "toggled", + * G_CALLBACK (output_state), NULL); + * gtk_box_pack_start (GTK_BOX (GTK_DIALOG (dialog)->action_area), + * toggle2, FALSE, FALSE, 2); + * + * gtk_widget_show_all (dialog); + * } + * + * + */ + + #define DEFAULT_LEFT_POS 4 #define DEFAULT_TOP_POS 4 #define DEFAULT_SPACING 7 @@ -143,6 +195,13 @@ gtk_toggle_button_class_init (GtkToggleButtonClass *class) FALSE, GTK_PARAM_READWRITE)); + /** + * GtkToggleButton::toggled: + * @togglebutton: the object which received the signal. + * + * Should be connected if you wish to perform an action whenever the + * #GtkToggleButton's state is changed. + */ toggle_button_signals[TOGGLED] = g_signal_new (I_("toggled"), G_OBJECT_CLASS_TYPE (gobject_class), @@ -216,13 +275,27 @@ gtk_toggle_button_sync_action_properties (GtkActivatable *activatable, gtk_action_unblock_activate (action); } - +/** + * gtk_toggle_button_new: + * + * Creates a new toggle button. A widget should be packed into the button, as in gtk_button_new(). + * + * Returns: a new toggle button. + */ GtkWidget* gtk_toggle_button_new (void) { return g_object_new (GTK_TYPE_TOGGLE_BUTTON, NULL); } +/** + * gtk_toggle_button_new_with_label: + * @label: a string containing the message to be placed in the toggle button. + * + * Creates a new toggle button with a text label. + * + * Returns: a new toggle button. + */ GtkWidget* gtk_toggle_button_new_with_label (const gchar *label) { @@ -369,6 +442,15 @@ gtk_toggle_button_get_mode (GtkToggleButton *toggle_button) return toggle_button->priv->draw_indicator; } +/** + * gtk_toggle_button_set_active: + * @toggle_button: a #GtkToggleButton. + * @is_active: %TRUE or %FALSE. + * + * Sets the status of the toggle button. Set to %TRUE if you want the + * GtkToggleButton to be 'pressed in', and %FALSE to raise it. + * This action causes the toggled signal to be emitted. + */ void gtk_toggle_button_set_active (GtkToggleButton *toggle_button, gboolean is_active) @@ -392,6 +474,15 @@ _gtk_toggle_button_set_active (GtkToggleButton *toggle_button, toggle_button->priv->active = is_active; } +/** + * gtk_toggle_button_get_active: + * @toggle_button: a #GtkToggleButton. + * + * Queries a #GtkToggleButton and returns its current state. Returns %TRUE if + * the toggle button is pressed in and %FALSE if it is raised. + * + * Returns: a #gboolean value. + */ gboolean gtk_toggle_button_get_active (GtkToggleButton *toggle_button) { @@ -400,7 +491,14 @@ gtk_toggle_button_get_active (GtkToggleButton *toggle_button) return toggle_button->priv->active; } - +/** + * gtk_toggle_button_toggled: + * @toggle_button: a #GtkToggleButton. + * + * Emits the #GtkToggleButton::toggled signal on the + * #GtkToggleButton. There is no good reason for an + * application ever to call this function. + */ void gtk_toggle_button_toggled (GtkToggleButton *toggle_button) { -- 2.30.2